//
//  NSFileManager+FWPowerful.h
//  iOSToolkit
//
//  Created by Evan Xie on 3/13/15.
//  Copyright (c) 2015 Family Wings. All rights reserved.
//

#import <Foundation/Foundation.h>


/** 
 This enumeration is mainly used to filter file url during scanning a directory. You can specify one,
 and related method returns the right file urls which are filtered by it.
 */
typedef NS_ENUM(NSUInteger, FileURLType) {
    /** A regular file or directory */
    FileURLTypeRegularFileAndDirectory,
    
    /** A regular file(eg. /My Heart Will Go On.mp3), it's fileAttributes[`NSFileType`] is equal `NSFileTypeRegular`. */
    FileURLTypeRegularFile,
    
    /** A directory(eg. /Videos), it's fileAttributes[`NSFileType`] is equal `NSFileTypeDirectory`. */
    FileURLTypeDirectory
};


/**
 A category for enhancing `NSFileManger` functions, make it much more convenient.
 */
@interface NSFileManager (FWPowerful)

/**
 Enumerates the specified directoryURL, then return back a fileArray with __NSURL__ objects which meet the conditions.
 
 Default, this method performs a deep enumeration. so if you need perform a shallow enumeration, please let `enumerationOptions` 
 or with `NSDirectoryEnumerationSkipsSubdirectoryDescendants`(ie. enumerationOptions |= NSDirectoryEnumerationSkipsSubdirectoryDescendants).
 
 @param directoryURL            The directory you want to enumerate.
 @param keys                    The properties like `NSURLIsDirectoryKey`, `NSURLNameKey`, and so on.
 @param enumerationOptions      @see NSDirectoryEnumerationOptions
 @param fileURLType             Which type of file URL you want to get.
 
 @return An array containing zero or multiple __NSURL__ objects.
 
 @note You can use [NSURL getResourceValue:forKey:error:] to get file attributes.
  */
+ (NSArray *)fileURLsOfDirectoryAtURL:(NSURL *)directoryURL
              includingPropertiesKeys:(NSArray *)keys
                   enumerationOptions:(NSDirectoryEnumerationOptions)enumerationOptions
                          fileURLType:(FileURLType)fileURLType;

/**
 Enumerates the specified directoryURL, every time enumerates one out, the `resultBlock` you given is invoked, then you can get one fileURL
 from `resultBlock`.
 
 Default, this method performs a deep enumeration. so if you need perform a shallow enumeration, please let `enumerationOptions`
 or with `NSDirectoryEnumerationSkipsSubdirectoryDescendants`(ie. enumerationOptions |= NSDirectoryEnumerationSkipsSubdirectoryDescendants).
 
 @param directoryURL            The directory you want to enumerate.
 @param keys                    The properties like `NSURLIsDirectoryKey`, `NSURLNameKey`, and so on.
 @param enumerationOptions      @see NSDirectoryEnumerationOptions
 @param fileURLType             Which type of file URL you want to get.
 @param resultBlock             You can get the fileURLs enumerated out from this block one by one, until all the fileURLs are enumerated out,
                                or you set *stop = YES to stop enmerating. If you receives a nil fileURL, it says the enumeration finished or cancelled.
 
 @note You can use [NSURL getResourceValue:forKey:error:] to get file attributes.
 */
+ (void)enumerateAtDirectoryURL:(NSURL *)directoryURL
        includingPropertiesKeys:(NSArray *)keys
             enumerationOptions:(NSDirectoryEnumerationOptions)enumerationOptions
                    fileURLType:(FileURLType)fileURLType
                    resultBlock:(void (^)(NSURL *fileURL, BOOL *stop))resultBlock;


+ (NSURL *)nextAvailableURLForFileAtURL:(NSURL *)fileURL;

@end
